package com.ruoyi.system.service;

import java.util.List;
import java.util.Set;

import com.ruoyi.common.core.domain.entity.SysRole;
import com.ruoyi.system.domain.SysUserRole;

/**
 * 角色业务层接口定义了系统中与角色相关的各种操作方法。
 * 包括角色的查询、新增、修改、删除以及权限校验等功能。
 *
 * @author ruoyi
 */
public interface ISysRoleService {

    /**
     * 根据条件分页查询角色数据
     *
     * @param role 角色信息，用于构建查询条件
     * @return 符合条件的角色数据集合
     */
    public List<SysRole> selectRoleList(SysRole role);

    /**
     * 根据用户ID查询该用户所拥有的角色列表
     *
     * @param userId 用户唯一标识符
     * @return 该用户对应的角色列表
     */
    public List<SysRole> selectRolesByUserId(Long userId);

    /**
     * 根据用户ID查询该用户所拥有的角色权限字符串集合（如：system:user:list）
     *
     * @param userId 用户唯一标识符
     * @return 权限字符串集合
     */
    public Set<String> selectRolePermissionByUserId(Long userId);

    /**
     * 查询所有可用的角色信息
     *
     * @return 所有角色列表
     */
    public List<SysRole> selectRoleAll();

    /**
     * 根据用户ID获取该用户已分配角色的选择框列表（主要用于前端回显）
     *
     * @param userId 用户唯一标识符
     * @return 已选中的角色ID列表
     */
    public List<Long> selectRoleListByUserId(Long userId);

    /**
     * 通过角色ID查询具体的角色详细信息
     *
     * @param roleId 角色唯一标识符
     * @return 对应的角色对象信息
     */
    public SysRole selectRoleById(Long roleId);

    /**
     * 检查指定角色名称在当前系统中是否唯一
     *
     * @param role 待检查的角色信息
     * @return true表示唯一，false表示不唯一
     */
    public boolean checkRoleNameUnique(SysRole role);

    /**
     * 检查指定角色权限字符在当前系统中是否唯一
     *
     * @param role 待检查的角色信息
     * @return true表示唯一，false表示不唯一
     */
    public boolean checkRoleKeyUnique(SysRole role);

    /**
     * 校验目标角色是否允许进行某些敏感操作（例如超级管理员角色不能被随意更改）
     *
     * @param role 待校验的角色信息
     */
    public void checkRoleAllowed(SysRole role);

    /**
     * 校验当前登录用户对给定角色ID的数据访问范围权限
     *
     * @param roleIds 被校验的角色ID数组
     */
    public void checkRoleDataScope(Long... roleIds);

    /**
     * 统计某个角色下已经绑定的用户数量
     *
     * @param roleId 角色唯一标识符
     * @return 使用该角色的用户数
     */
    public int countUserRoleByRoleId(Long roleId);

    /**
     * 插入一个新的角色记录到数据库中
     *
     * @param role 待插入的角色信息
     * @return 影响的行数
     */
    public int insertRole(SysRole role);

    /**
     * 更新已有角色的基本信息
     *
     * @param role 待更新的角色信息
     * @return 影响的行数
     */
    public int updateRole(SysRole role);

    /**
     * 修改角色的状态（启用/禁用）
     *
     * @param role 包含新状态的角色信息
     * @return 影响的行数
     */
    public int updateRoleStatus(SysRole role);

    /**
     * 授权角色的数据访问范围配置
     *
     * @param role 包含新的数据权限设置的角色信息
     * @return 影响的行数
     */
    public int authDataScope(SysRole role);

    /**
     * 根据角色ID从数据库中逻辑或物理删除一个角色
     *
     * @param roleId 待删除角色的唯一标识符
     * @return 影响的行数
     */
    public int deleteRoleById(Long roleId);

    /**
     * 批量删除多个角色信息
     *
     * @param roleIds 需要删除的角色ID数组
     * @return 影响的行数
     */
    public int deleteRoleByIds(Long[] roleIds);

    /**
     * 删除特定用户的某项角色授权关系
     *
     * @param userRole 用户和角色之间的关联实体
     * @return 影响的行数
     */
    public int deleteAuthUser(SysUserRole userRole);

    /**
     * 批量移除一批用户对该角色的授权关系
     *
     * @param roleId  目标角色ID
     * @param userIds 需要取消授权的用户ID数组
     * @return 影响的行数
     */
    public int deleteAuthUsers(Long roleId, Long[] userIds);

    /**
     * 批量为一组用户授予指定角色权限
     *
     * @param roleId  目标角色ID
     * @param userIds 需要授权的用户ID数组
     * @return 影响的行数
     */
    public int insertAuthUsers(Long roleId, Long[] userIds);
}
